SGI Freeware 1999 November

home *** CD-ROM | disk | FTP | other *** search

/ SGI Freeware 1999 November / SGI Freeware 1999 November - Disc 1.iso / dist / fw_teTeX.idb / usr / freeware / info / dvips.info-2.z / dvips.info-2

(.txt)

Wrap

GNU Info File | 1999-10-18 | 48KB | 879 lines

This is Info file dvips.info, produced by Makeinfo version 1.68 from the input file dvips.texi. INFO-DIR-SECTION TeX START-INFO-DIR-ENTRY * DVI-to-Postscript: (dvips). Translating TeX DVI files to PostScript. * afm2tfm: (dvips)Invoking afm2tfm. Making Type 1 fonts available to TeX. * dvips: (dvips)Invoking Dvips. DVI-to-PostScript translator. END-INFO-DIR-ENTRY File: dvips.info, Node: Configuration file commands, Prev: Configuration file searching, Up: Config files Configuration file commands --------------------------- Most of the configuration file commands are similar to corresponding command line options, but there are a few exceptions. When they are the same, we omit the description here. As with command line options, many may be turned off by suffixing the letter with a zero (`0'). Within a configuration file, empty lines, and lines starting with a space, asterisk, equal sign, percent sign, or pound sign are ignored. There is no provision for continuation lines. `@ NAME HSIZE VSIZE' Define paper sizes. *Note Config file paper sizes::. Memory conservation. Same as `-a', *note Option details::.. `b #COPIES' Multiple copies. Same as `-b', *note Option details::.. `D DPI' Output resolution. Same as `-D', *note Option details::.. `e NUM' Max drift. Same as `-e', *note Option details::.. `E COMMAND' Executes the command listed with `system'(3); can be used to get the current date into a header file for inclusion, for instance. Possibly dangerous; this may be disabled, in which case a warning will be printed if the option is used (and warnings are not suppressed). Run as a filter. Same as `-f', *note Option details::.. `h HEADER' Prepend HEADER to output. Same as `h-', *note Option details::.. `H PATH' Use PATH to search for PostScript header files. The environment variable `DVIPSHEADERS' overrides this. `i N' Make multiple output files. Same as `-i -S N', *note Option details::.. Partially download Type 1 fonts. Same as `-j', *note Option details::.. Remove comments from included PostScript files. Same as `-K', *note Option details::.. `m NUM' Declare NUM as the memory available for fonts and strings in the printer. Default is 180000. This value must be accurate if memory conservation and document splitting is to work correctly. To determine this value, send the following file to the printer: %! Hey, we're PostScript /Times-Roman findfont 30 scalefont setfont 144 432 moveto vmstatus exch sub 40 string cvs show pop showpage The number printed by this file is the total memory free; it is usually best to tell Dvips that the printer has slightly less memory, because many programs download permanent macros that can reduce the memory in the printer. Some systems or printers can dynamically increase the memory available to a PostScript interpreter, in which case this file might return a ridiculously low number; for example, the NeXT computer and Ghostscript. In these cases, a value of one million works fine. `M MODE' Metafont mode. Same as `-mode', *note Option details::.. Disable structured comments. Beware: This also turns off displaying page numbers or changing to specific pagenumbers in PostScript viewers. Same as `-N', *note Option details::.. `o NAME' Send output to NAME. Same as `-', *note Option details::.. In the file `config.foo', a setting like this is probably appropriate: o |lpr -Pfoo The MS-DOS version will emulate spooling to `lpr' by printing to the local printer device `PRN' if it doesn't find an executable program by that name in the current directory or along the `PATH'. `O XOFF,YOFF' Origin offset. Same as `-O', *note Option details::.. `p [+]NAME' Examine NAME for PostScript font aliases. Default is `psfonts.map'. This option allows you to specify different resident fonts that different printers may have. If NAME starts with a `+' character, then the rest of the name (after any leading spaces) is used as an additional map file; thus, it is possible to have local map files pointed to by local configuration files that append to the global map file. This can be used for font families. `P PATH' Use PATH to search for bitmap PK font files is PATH. The `PKFONTS', `TEXPKS', `GLYPHFONTS', and `TEXFONTS' environment variables override this. *Note Supported file formats: (kpathsea)Supported file formats. Run quietly. Same as `-q', *note Option details::.. Page reversal. Same as `-r', *note Option details::.. `R NUM1 NUM2 ...' Define the list of default resolutions for PK fonts. If a font size actually used in a document is not available and cannot be created, Dvips will scale the font found at the closest of these resolutions to the requested size, using PostScript scaling. The resulting output may be ugly, and thus a warning is issued. To turn this last-resort scaling off, use a line with just the `R' and no numbers. The given numbers must be sorted in increasing order; any number smaller than the preceding one is ignored. This is because it is better to scale a font up than down; scaling down can obliterate small features in the character shape. The environment and config file values `DVIPSSIZES' or `TEXSIZES' override this configuration file setting. If no `R' settings or environment variables are specified, a list compiled in during installation is used. This default list is defined by the Makefile variable `default_texsizes', defined in the file `make/paths.make'. Output global save/restore. Same as `-s', *note Option details::.. `S PATH' Use PATH to search for special illustrations (Encapsulated PostScript files or psfiles). The `TEXPICTS' and then `TEXINPUTS' environment variables override this. `T PATH' Use PATH to search for TFM files. The `TFMFONTS' and then `TEXFONTS' environment variables overrides this. This path is used for resident fonts and fonts that can't otherwise be found. Work around bug in Xerox 4045 printer. Same as `-U', *note Option details::.. `V PATH' Use PATH to search for virtual font files. This may be device-dependent if you use virtual fonts to simulate actual fonts on different devices. `W [STRING]' If STRING is supplied, write it to standard error after reading all the configuration files; with no STRING, cancel any previous `W' message. This is useful in the default configuration file to remind users to specify a printer, for instance, or to notify users about special characteristics of a particular printer. `X NUM' Horizontal resolution. Same as `-X', *note Option details::.. `Y NUM' Vertical resolution. Same as `-Y', *note Option details::.. Compress bitmap fonts. Same as `-Z', *note Option details::.. File: dvips.info, Node: Paper size and landscape, Next: Interaction with PostScript, Prev: Invoking Dvips, Up: Top Paper size and landscape orientation ************************************ Most TeX documents at a particular site are designed to use the standard paper size (letter size in the United States, A4 in Europe). The Dvips program can be customized either sitewide or for a particular printer. But many documents are designed for other paper sizes. For instance, you may want to design a document that has the long edge of the paper horizontal. This can be useful when typesetting booklets, brochures, complex tables, or many other documents. This type of paper orientation is called "landscape" orientation (the default orientation is "portrait"). Alternatively, a document might be designed for ledger or A3 paper. Since the intended paper size is a document design decision, not a printing decision, such information should be given in the TeX file and not on the Dvips command line. For this reason, Dvips supports a `papersize' special. It is hoped that this special will become standard over time for TeX previewers and other printer drivers. * Menu: * papersize special:: Specifying the paper size in TeX. * Config file paper sizes:: Specifying printer- and site-specific sizes. * Paper trays:: Changing paper trays automatically. File: dvips.info, Node: papersize special, Next: Config file paper sizes, Up: Paper size and landscape `papersize' special =================== The format of the `papersize' special is \special{papersize=WIDTH,HEIGHT} WIDTH is the horizontal size of the page, and HEIGHT is the vertical size. The dimensions supported are the same as for TeX; namely, in (inches), cm (centimeters), mm (millimeters), pt (points), sp (scaled points), bp (big points, the same as the default PostScript unit), pc (picas), dd (didot points), and cc (ciceros). For a US letter size landscape document, the `papersize' would be: \special{papersize=11in,8.5in} An alternate specification of `landscape': \special{landscape} This is supported for backward compatibility, but it is hoped that reventually the `papersize' comment will dominate. Of course, such a `\special' only informs Dvips of the desired paper size; you must also adjust `\hsize' and `\vsize' in your TeX document typeset to those dimensions. The `papersize' special must occur somewhere on the first page of the document. File: dvips.info, Node: Config file paper sizes, Next: Paper trays, Prev: papersize special, Up: Paper size and landscape Configuration file paper size command ===================================== The `@' command in a configuration file sets the paper size defaults and options. The first `@' command defines the default paper size. It has three possible parameters: @ [NAME [HSIZE VSIZE]] If `@' is specified on a line by itself, with no parameters, it instructs Dvips to discard all previous paper size information (possibly from another configuration file). If three parameters are given, with the first parameter being a name and the second and third being a dimension (as in `8.5in' or `3.2cc', just like in the `papersize' special), then the option is interpreted as starting a new paper size description, where NAME is the name and HSIZE and VSIZE define the horizontal and vertical size of the sheet of paper, respectively. For example: @ letterSize 8.5in 11in If both HSIZE and VSIZE are zero (you must still specify units!) then any page size will match. If the `@' character is immediately followed by a `+' sign, then the remainder of the line (after skipping any leading blanks) is treated as PostScript code to send to the printer, presumably to select that particular paper size: @ letter 8.5in 11in @+ %%BeginPaperSize: Letter @+ letter @+ %%EndPaperSize After all that, if the first character of the line is an exclamation point, then the line is put in the initial comments section of the final output file; else, it is put in the setup section of the output file. For example: @ legal 8.5in 14in @+ ! %%DocumentPaperSizes: Legal @+ %%BeginPaperSize: Legal @+ legal @+ %%EndPaperSize When Dvips has a paper format name given on the command line, it looks for a match by the NAME; when it has a `papersize' special, it looks for a match by dimensions. The first match found (in the order the paper size information is found in the configuration file) is used. If nothing matches, a warning is printed and the first paper size is used. The dimensions must match within a quarter of an inch. Landscape mode for all paper sizes is automatically supported. If your printer has a command to set a special paper size, then give dimensions of `0in 0in'; the PostScript code that sets the paper size can refer to the dimensions the user requested as `hsize' and `vsize'; these will be macros defined in the PostScript that return the requested size in default PostScript units. Virtually all of the PostScript commands you use here are device-dependent and degrade the portability of the file; that is why the default first paper size entry should not send any PostScript commands down (although a structured comment or two would be okay). Also, some printers want `BeginPaperSize' comments and paper size setting commands; others (such as the NeXT) want `PaperSize' comments and they will handle setting the paper size. There is no solution I could find that works for both (except maybe specifying both). The Perl 5 script `contrib/mkdvipspapers' in the distribution directory may help in determining appropriate paper size definitions. If your printers are configured to use A4 paper by default, the configuration file (probably the global `config.ps' in this case) should include this as the first `@' command: @ A4size 210mm 297mm @+ %%PaperSize: A4 so that `A4size' is used as the default, and not `A4' itself; thus, no PostScript `a4' command is added to the output file, unless the user explicitly says to use paper size `a4'. That is, by default, no paper size PostScript command should be put in the output, but Dvips will still know that the paper size is A4 because `A4size' is the first (and therefore default) size in the configuration file. Executing the `letter' or `a4' or other PostScript operators cause the document to be nonconforming and can cause it not to print on certain printers, so the default paper size should not execute such an operator if at all possible. File: dvips.info, Node: Paper trays, Prev: Config file paper sizes, Up: Paper size and landscape Paper trays =========== Some printers, such as the Hewlett-Packard HP4si, have multiple paper trays. You can set up Dvips to take advantage of this using the `bop-hook' PostScript variable (*note PostScript hooks::.). For example, suppose you have an alternate tray stocked with letterhead paper; the usual tray has the usual paper. You have a document where you want the first page printed on letterhead, and the remaining pages on the usual paper. You can create a header file, say `firstletterhead.PS', with the following (PostScript) code (`bop-hook' is passed the current physical page number, which starts at zero): /bop-hook { dup 0 eq { ALTERNATETRAY } { NORMALTRAY } ifelse } def where ALTERNATETRAY and NORMALTRAY are the appropriate commands to select the paper trays. On the 4SI, ALTERNATETRAY is `statusdict begin 1 setpapertray end' and NORMALTRAY is `statusdict begin 0 setpapertray end'. Then, include the file with either * the `-h' command-line option (*note Option details::.); or * the `h' config file option (*note Configuration file commands::.); or * `\special{header=FILE}' in your TeX document (*note Including headers from TeX: Including headers from TeX.). File: dvips.info, Node: Interaction with PostScript, Next: PostScript fonts, Prev: Paper size and landscape, Up: Top Interaction with PostScript *************************** Dvips supports inclusion of PostScript figure files (e.g., Encapsulated PostScript), downloading other header files (e.g., fonts), including literal PostScript code, and hypertext. * Menu: * PostScript figures:: Including an Encapsulated PostScript figure. * Header files:: Downloading extra definitions. * Literal PS:: Writing literal PostScript code. * Hypertext:: Producing HyperPostScript to make PDF. File: dvips.info, Node: PostScript figures, Next: Header files, Up: Interaction with PostScript PostScript figures ================== Scaling and including PostScript graphics is a breeze--if the PostScript file is correctly formed. Even if it is not, however, the file can usually be accommodated with just a little more work. * Menu: * Bounding box:: The %%BoundingBox EPS comment. * EPSF macros:: Including the file in TeX. * psfile special:: The basic special. * Dynamic creation of graphics:: Handling compressed or generated figures. * Fonts in figures:: The %*Font comment. File: dvips.info, Node: Bounding box, Next: EPSF macros, Up: PostScript figures The bounding box comment ------------------------ The most important feature of a good PostScript file from the standpoint of including it in another document is an accurate bounding box comment. Every well-formed PostScript file has a comment describing where on the page the graphic is located, and how big that graphic is. This information is given as the lower left and upper right corners of the box just enclosing the graphic, and is thus referred to as the "bounding box". These coordinates are given in the default PostScript units (there are precisely 72 PostScript units to the inch, like TeX big points) with respect to the lower left corner of the sheet of paper. To see if a PostScript file has a bounding box comment, just look at the first few lines of the file. PostScript files are standard ASCII, so you can use any text editor to do this. If within the first few dozen lines there is a line like %%BoundingBox: 25 50 400 300 (with any reasonable numbers), chances are very good that the file is Encapsulated PostScript and will work easily with Dvips. If the file contains instead a line like %%BoundingBox: (atend) the file is still probably Encapsulated PostScript, but the bounding box is given at the end of the file. Dvips needs it at the beginning. You can move it with that same text editor, or a simple script. (The bounding box is given in this way when the program that generated the PostScript couldn't know the size in advance, or was too lazy to compute If the document lacks a `%%BoundingBox:' altogether, you can determine one in a couple of ways. One is to use the `bbfig' program distributed with Dvips in the `contrib' directory. This can usually find the correct bounding box automatically; it works best with Ghostscript. If the comment looks like this: %%BoundingBox: 0 0 612 792 the graphic claims to take up an entire sheet of paper. This is usually a symptom of a bug in the program that generated it. The other is to do it yourself: print the file. Now, take a ruler, and make the following measurements (in PostScript units, so measure in inches and multiply by 72): From the left edge of the paper to the leftmost mark on the paper is LLX, the first number. From the bottom edge of the paper to the bottommost mark on the paper is LLY, the second number. From the left edge of the paper to the rightmost mark on the paper is URX, the third number. The fourth and final number, URY, is the distance from the bottom of the page to the uppermost mark on the paper. Once you have the numbers, add a comment of the following form as the second line of the document. (The first line should already be a line starting with the two characters `%!'; if it is not, the file probably isn't PostScript.) %%BoundingBox: LLX LLY URX URY Or, if you don't want to modify the file, you can simply write these numbers down in a convenient place and give them in your TeX document when you import the graphic, as described in the next section. If the document does not have such a bounding box, or if the bounding box is given at the end of the document, or the bounding box is wrong, please complain to the authors of the software package that generated the file. File: dvips.info, Node: EPSF macros, Next: psfile special, Prev: Bounding box, Up: PostScript figures Using the EPSF macros --------------------- Once the figure file has a bounding box comment (see the previous section,) you are ready it the graphic into a TeX document. Many packages for using EPS files exist. One distributed with Dvips is the files `epsf.tex' (for plain TeX) and `epsf.sty' (for LaTeX). For plain TeX, add a line like this near the top of your input file: \input epsf If you are using LaTeX 2e, use the `graphics' or `graphicx' package. If you are using LaTeX 2.09, add the `epsf' style option, as in: \documentstyle[12pt,epsf]{article} In any case, the above only needs to be done once, no matter how many figures you plan to include. Now, at the point you want to include a file, enter a line such as: \epsffile{foo.eps} If you are using LaTeX, you may need to add `\leavevmode' immediately before the `\epsffile' command to get certain environments to work correctly. If your file does not have a bounding box comment, you can supply the numbers as determined in the previous section, in the same order they would have been in a normal bounding box comment: \epsffile[100 100 500 500]{foo.ps} Now, save your changes and run TeX and Dvips; the output should have your graphic positioned at precisely the point you indicated, occupying the proper amount of space. The `\epsffile' macro typesets the figure as a TeX `\vbox' at the point of the page that the command is executed. By default, the graphic will have its `natural' width (namely, the width of its bounding box). The TeX box will have depth zero and its natural height. By default, the graphic will be scaled by any DVI magnification in effect, just as is everything else in your document. See the next section for more information on scaling. If you want TeX to report the size of the figure as a message on your terminal when it processes each figure, give the command: \epsfverbosetrue * Menu: * EPSF scaling:: * EPSF clipping:: File: dvips.info, Node: EPSF scaling, Next: EPSF clipping, Up: EPSF macros EPSF scaling ............ Usually, you will want to scale an EPSF figure to some size appropriate for your document, since its natural size is determined by the creator of the EPS file. The best way to do this is to assign the desired size to the TeX `\epsfxsize' or `\epsfysize' variables, whichever is more convenient for you. That is, put \epsfxsize=DIMEN right before the call to `\epsffile'. Then the width of the TeX box will be DIMEN and its height will be scaled proportionately. Similarly, you can set the vertical size with \epsfysize=DIMEN in which case the height will be set and the width scaled proportionally. If you set both, both will be honored, but the aspect ratio of the included graphic may necessarily be distorted, i.e., its contents stretched in one direction or the other. You can resize graphics in a more general way by redefining the `\epsfsize' macro. `\epsffile' calls this with two parameters: the natural horizontal and vertical sizes of the PostScript graphic. `\epsfsize' must expand to the desired horizontal size, that is, the width of the `\vbox'. Schematically: \def\epsfsize#1#2{BODY} Some useful definitions of BODY: `\epsfxsize' This definition (the default) enables the default features listed above, by setting `\epsfxsize' to the same value it had before the macro was called. Force the natural size by returning the first parameter (the original width). `0pt' A special case, equivalent to `#1'. `0.5#1' Scale to half the natural size. `\hsize' Scale to the current `\hsize'. (In LaTeX, use `\textwidth' instead of `\hsize'.) `\ifnum#1>\hsize\hsize\else#1\fi' If the natural width is greater than the current `\hsize', scale to `\hsize', otherwise use the natural width. For compatibility with other PostScript drivers, it is possible to turn off the default scaling of included figures by the DVI magnification with the following TeX command: \special{! /magscale false def} Use of this command is not recommended because it will make the `\epsffile' graphics the "wrong" size if global magnification is being used, and it will cause any PostScript graphics to appear improperly scaled and out of position if a DVI to DVI program is used to scale or otherwise modify the document. DVI magnification is not applied to any output from code you write in `bop-hook' or its ilk (*note PostScript hooks::.), File: dvips.info, Node: EPSF clipping, Prev: EPSF scaling, Up: EPSF macros EPSF clipping ............. By default, clipping is disabled for included EPSF images. This is because clipping to the bounding box dimensions often cuts off a small portion of the figure, due to slightly inaccurate bounding box arguments. The problem might be subtle; lines around the boundary of the image might be half their intended width, or the tops or bottoms of some text annotations might be sliced off. If you want to turn clipping on, just use the command \epsfclipon and to turn clipping back off, use \epsfclipoff File: dvips.info, Node: psfile special, Next: Dynamic creation of graphics, Prev: EPSF macros, Up: PostScript figures `psfile' special ---------------- The basic special for file inclusion is as follows: \special{psfile=FILENAME.ps [KEY=VALUE] ... } This downloads the PostScript file `FILENAME.ps' such that the current point will be the origin of the PostScript coordinate system. The optional KEY=VALUE assignments allow you to specify transformations on the PostScript. The possible KEYs are: `hoffset' The horizontal offset (default 0) `voffset' The vertical offset (default 0) `hsize' The horizontal clipping size (default 612) `vsize' The vertical clipping size (default 792) `hscale' The horizontal scaling factor (default 100) `vscale' The vertical scaling factor (default 100) `angle' The rotation (default 0) `clip' Enable clipping to the bounding box The dimension parameters are all given in PostScript units. The `hscale' and `vscale' are given in non-dimensioned percentage units, and the rotation value is specified in degrees. Thus \special{psfile=foo.ps hoffset=72 hscale=90 vscale=90} will shift the graphics produced by file `foo.ps' right by one inch and will draw it at 0.9 times normal size. Offsets are given relative to the point of the special command, and are unaffected by scaling or rotation. Rotation is counterclockwise about the origin. The order of operations is to rotate the figure, scale it, then offset it. For compatibility with older PostScript drivers, it is possible to change the units that `hscale' and `vscale' are given in. This can be done by redefining `@scaleunit' in `SDict' by a TeX command such as \special{! /@scaleunit 1 def} The `@scaleunit' variable, which is by default 100, is what `hscale' and `vscale' are divided by to yield an absolute scale factor. File: dvips.info, Node: Dynamic creation of graphics, Next: Fonts in figures, Prev: psfile special, Up: PostScript figures Dynamic creation of PostScript graphics files --------------------------------------------- PostScript is an excellent page description language--but it does tend to be rather verbose. Compressing PostScript graphics files can reduce them by factor of five or more. For this reason, if the name of an included PostScript file ends with `.Z' or `.gz', Dvips automatically runs `gzip -d'. For example: \epsffile[72 72 540 720]{foo.ps.gz} Since the results of such a command are not accessible to TeX, if you use this facility with the `epsf' macros, you need to supply the bounding box parameter yourself, as shown. More generally, if the filename parameter to one of the graphics inclusion techniques starts with a left quote (``'), the parameter is instead interpreted as a command to execute that will send the actual file to standard output. For example: \special{psfile="`gnuplot foo"} to include the file `foo'. Of course, the command to be executed can be anything, including using a file conversion utility such as `tek2ps' or whatever is appropriate. This feature can be disabled with the `-R' command-line option or `R' configuration option. File: dvips.info, Node: Fonts in figures, Prev: Dynamic creation of graphics, Up: PostScript figures Fonts in figures ---------------- You can use any font available to TeX and Dvips within a graphics file by putting a `%*Font:' line in the leading commentary of the file. Schematically, this looks like: %*Font: TFMNAME SCALEDBP DESIGNBP HEX-START:HEX-BITSTRING Here is the meaning of each of these elements: TFMNAME The TeX TFM filename, e.g., `cmr10'. You can give the same TFMNAME on more than one `%*Font' line; this is useful when the number of characters from the font used needs a longer HEX-BITSTRING (see item below) than conveniently fits on one line. SCALEDBP The size at which you are using the font, in PostScript points (TeX big points). 72bp = 72.27pt = 1in. DESIGNBP The designsize of the font, again in PostScript points. This should match the value in the TFM file TFMNAME. Thus, for `cmr10', it should be `9.96265'. HEX-START The character code of the first character used from the font, specified as two ASCII hexadecimal characters, e.g., `4b' or `4B' for `K'. HEX-BITSTRING An arbitrary number of ASCII hexadecimal digits specifying which characters following (and including) HEX-START are used. This is treated as a bitmap. For example, if your figure used the single letter `K', you would use `4b:8' for HEX-START and HEX-BITSTRING. If it used `KLMNP', you would use `4b:f4'. MetaPost's output figures contain lines like this for bitmap fonts used in a MetaPost label (*note MetaPost: (web2c)MetaPost.). File: dvips.info, Node: Header files, Next: Literal PS, Prev: PostScript figures, Up: Interaction with PostScript PostScript header files ======================= "Header files" are bits of PostScript included in the output file; generally they provide support for special features, rather than producing any printed output themselves. You can explicitly request downloading header files if necessary for some figure, or to achieve some special effect. Dvips includes some headers on its own initiative, to implement features such as PostScript font reencoding, bitmap font downloading, handling of `\special''s, and so on. These standard headers are the `.pro' files (for "prologue") in the installation directory `$(psheaderdir)'; they are created from the `.lpro' ("long prologue") files in the distribution by stripping comments, squeezing blank lines, etc., for maximum efficiency. If you want to peruse one of the standard header files, read the `.lpro' version. The PostScript dictionary stack will be at the `userdict' level when header files are included. * Menu: * Including headers from TeX:: * Including headers from the command line:: * Headers and memory usage:: File: dvips.info, Node: Including headers from TeX, Next: Including headers from the command line, Up: Header files Including headers from TeX -------------------------- In order to get a particular graphic file to work, a certain font or header file might need to be sent first. The Dvips program provides support for this with the `header' `\special'. For instance, to ensure that `foo.ps' gets downloaded: \special{header=foo.ps} As another example, if you have some PostScript code that uses a PostScript font not built into your printer, you must download it to the printer. If the font isn't used elsewhere in the document, Dvips can't know you've used it, so you must include it in the same way, as in: \special{header=putr.pfa} to include the font definition file for Adobe Utopia Roman. File: dvips.info, Node: Including headers from the command line, Next: Headers and memory usage, Prev: Including headers from TeX, Up: Header files Including headers from the command line --------------------------------------- You can include headers when you run Dvips, as well as from your document (see the previous section). To do this, run Dvips with the option `-P HEADER'; this will read the file `config.HEADER', which in turn can specify a header file to be downloaded with the `h' option. *Note Configuration file commands::. These files are called `HEADER.cfg' on MS-DOS. You can arrange for the same file to serve as a `-P' config file and the downloadable header file, by starting the lines of PostScript code with a space, leaving only the `h' line and any comments starting in the first column. As an example, see `contrib/volker/config.*' (`contrib/volker/*.cfg' on MS-DOS). (These files also perform useful functions: controlling duplex/simplex mode on duplex printers, and setting various screen frequencies; `contrib/volker/README' explains further.) File: dvips.info, Node: Headers and memory usage, Prev: Including headers from the command line, Up: Header files Headers and memory usage ------------------------ Dvips tries to avoid overflowing the printer's memory by splitting the output files into "sections" (see the `-i' option in *Note Option details::). Therefore, for all header files, Dvips debits the printer VM budget by some value. If the header file has, in its leading commentary a line of the form %%VMusage: MIN MAX then MAX is used. If there is no `%%VMusage' line, then the size (in bytes) of the header file is used as an approximation. Illustrations (figure files) are also checked for `%%VMusage' line. File: dvips.info, Node: Literal PS, Next: Hypertext, Prev: Header files, Up: Interaction with PostScript Literal PostScript ================== You can include literal PostScript code in your document in several ways. * Menu: * " special:: To include inline PostScript code. * ps special:: Inline PostScript without save/restore. * PostScript hooks:: Specifying code to run in the PS interpreter. * Literal headers:: Literal PostScript for the whole document. * Literal examples:: Neat example. File: dvips.info, Node: " special, Next: ps special, Up: Literal PS `"' special: Literal PostScript ------------------------------- For simple graphics, or just for experimentation, literal PostScript code can be included. Simply use a `\special' beginning with a double quote character `"'; there is no matching closing `"'. For instance, the following (simple) graphic: [ picture of a grey triangle ] was created by typing: \vbox to 100bp{\vss % a bp is the same as a PostScript unit \special{" newpath 0 0 moveto 100 100 lineto 394 0 lineto closepath gsave 0.8 setgray fill grestore stroke}} You are responsible for leaving space for such literal graphics, as with the `\vbox' above. File: dvips.info, Node: ps special, Next: PostScript hooks, Prev: " special, Up: Literal PS `ps' special ------------ Generally, Dvips encloses specials in a PostScript save/restore pair, guaranteeing that the special will have no effect on the rest of the document. The `ps' special, however, allows you to insert literal PostScript instructions without this protective shield; you should understand what you're doing (and you shouldn't change the PostScript graphics state unless you are willing to take the consequences). This command can take many forms because it has had a torturous history; any of the following will work: \special{ps:TEXT} \special{ps::TEXT} \special{ps::[begin]TEXT} \special{ps::[end]TEXT} (with longer forms taking precedence over shorter forms, when they are present). `ps::' and `ps::[end]' do no positioning, so they can be used to continue PostScript literals started with `ps:' or `ps::[begin]'. In addition, the variant \special{ps: plotfile FILENAME} inserts the contents of FILENAME verbatim into the output (except for omitting lines that begin with %). An example of the proper use of literal specials can be found in the file `rotate.tex', which makes it easy to typeset text turned in multiples of 90 degrees. File: dvips.info, Node: Literal headers, Next: Literal examples, Prev: PostScript hooks, Up: Literal PS Literal headers: `!' `\special' ------------------------------- You can download literal PostScript header code in your TeX document, for use with (for example) literal graphics code that you include later. The text of a `\special' beginning with an `!' is copied into the output file. A dictionary `SDict' will be current when this code is executed; Dvips arranges for `SDict' to be first on the dictionary stack when any PostScript graphic is included, whether literally (the `"' special) or through macros (e.g., `epsf.tex'). For example: \special{! /reset { 0 0 moveto} def} File: dvips.info, Node: PostScript hooks, Next: Literal headers, Prev: ps special, Up: Literal PS PostScript hooks ---------------- Besides including literal PostScript at a particular place in your document (as described in the previous section), you can also arrange to execute arbitrary PostScript code at particular times while the PostScript is printing. If any of the PostScript names `bop-hook', `eop-hook', `start-hook', or `end-hook' are defined in `userdict', they will be executed at the beginning of a page, end of a page, start of the document, and end of a document, respectively. When these macros are executed, the default PostScript coordinate system and origin is in effect. Such macros can be defined in headers added by the `-h' option or the `header=' special, and might be useful for writing, for instance, `DRAFT' across the entire page, or, with the aid of a shell script, dating the document. These macros are executed outside of the save/restore context of the individual pages, so it is possible for them to accumulate information, but if a document must be divided into sections because of memory constraints, such added information will be lost across section breaks. The single argument to `bop-hook' is the physical page number; the first page gets zero, the second one, etc. `bop-hook' must leave this number on the stack. None of the other hooks are passed arguments. As an example of what can be done, the following special will write a light grey `DRAFT' across each page in the document: \special{!userdict begin /bop-hook{gsave 200 30 translate 65 rotate /Times-Roman findfont 216 scalefont setfont 0 0 moveto 0.7 setgray (DRAFT) show grestore}def end} Using `bop-hook' or `eop-hook' to preserve information across pages breaks compliance with the Adobe document structuring conventions, so if you use any such tricks, you may also want to use the `-N' option to turn off structured comments (such as `%%Page'). Otherwise, programs that read your file will assume its pages are independent. File: dvips.info, Node: Literal examples, Prev: Literal headers, Up: Literal PS Literal examples ---------------- To finish off this section, the following examples of literal PostScript are presented without explanation: \def\rotninety{\special{ps:currentpoint currentpoint translate 90 rotate neg exch neg exch translate}}\font\huge=cmbx10 at 14.4truept \setbox0=\hbox to0pt{\huge A\hss}\vskip16truept\centerline{\copy0 \special{ps:gsave}\rotninety\copy0\rotninety\copy0\rotninety \box0\special{ps:grestore}}\vskip16truept [ There are 4 `A' characters, each rotated 90 degrees about a common center point ] \vbox to 2truein{\special{ps:gsave 0.3 setgray}\hrule height 2in width\hsize\vskip-2in\special{ps:grestore}\font\big=cminch\big \vss\special{ps:gsave 1 setgray}\vbox to 0pt{\vskip2pt \line{\hss\hskip4pt NEAT\hss}\vss}\special{ps:0 setgray}% \hbox{\raise2pt\line{\hss NEAT\hss}\special{ps:grestore}}\vss} [ There is a big gray box with the word `NEAT' inside in big letters ] Some caveats are in order, however. Make sure that each `gsave' is matched with a `grestore' on the same page. Do not use `save' and `restore'; they can interact with the PostScript generated by Dvips if care is not taken. Try to understand what the above macros are doing before writing your own. The `\rotninety' macro especially has a useful trick that appears again and again. File: dvips.info, Node: Hypertext, Prev: Literal PS, Up: Interaction with PostScript HyperTeXt ========= Dvips has support for producing hypertext PostScript documents. If you specify the `-z' option, the `html:' specials described below will be converted into `pdfmark' PostScript operators to specify links. Without `-z', `html:' specials are ignored. The resulting PostScript can then be processed by a distiller program to make a PDF file. (It can still be handled by ordinary PostScript interpreters as well.) Various versions of both PC and Unix distillers are supported; Ghostscript includes limited distiller support (*note Ghostscript installation::.). Macros you can use in your TeX document to insert the specials in the first place are available from `CTAN:/support/hypertex'. For CTAN info, *note unixtex.ftp: (kpathsea)unixtex.ftp.. This hypertext support (and original form of the documentation) was written by Mark Doyle and Tanmoy Bhattacharya as the `dvihps' program. You can retrieve their software and additional documentation via the CTAN reference above. You may also be interested in the Java previewer IDVI, available at `http://www.win.tue.nl/~dickie/idvi', and/or in `http://www.emrg.com/texpdf.html', which describes the process of making PDF files from TeX files in more detail. Mail archives for the original project are at `http://math.albany.edu:8800/hm/ht/'. * Menu: * Hypertext caveats:: Bitmaps poorly supported, psi. * Hypertext specials:: The details on the specials. File: dvips.info, Node: Hypertext caveats, Next: Hypertext specials, Up: Hypertext Hypertext caveats ----------------- If you intend to go all the way to PDF, you will probably want to use PostScript fonts exclusively, since the Adobe PDF readers are extremely slow when dealing with bitmap fonts. Commercial versions of the Computer Modern fonts are available from Blue Sky; public domain versions are available from CTAN sites (for CTAN info, *note unixtex.ftp: (kpathsea)unixtex.ftp.) in: fonts/postscript/bakoma fonts/postscript/paradissa You may need to modify these fonts; see `http://xxx.lanl.gov/faq/bakoma.html'. Also, the Adobe distillers prior to 2.1 drop trailing space characters (character code 32) from strings. Unfortunately, the PostScript fonts use this character code for characters other than space (notably the Greek letter psi in the `Symbol' font), and so these characters are dropped. This bug is fixed in version 2.1. If you can't upgrade, One workaround is to change all the trailing blanks in strings to a character code that isn't in the font. This works because the default behavior is to substitute a blank for a missing character, i.e., the distiller is fooled into substituting the right character. For instance, with the Blue Sky fonts, you can globally replace ` )' with `\200)' (with `sed', for example) and get the desired result. With the public domain fonts, you will probably have to use a character code in the range 128 to 191 since these fonts duplicate the first 32 characters starting at 192 to avoid MS-DOS problems. File: dvips.info, Node: Hypertext specials, Prev: Hypertext caveats, Up: Hypertext Hypertext specials ------------------ Current support for the World Wide Web in the TeX system does not involve modifying TeX itself. We need only define some specials; Arthur Smith (<apsmith@aps.org>), Tanmoy Bhattacharya, and Paul Ginsparg originally proposed and implemented the following: html:<a href="XURL"> html:<a name="NAME"> html:</a> html:<img src="XURL"> html:<base href="XURL"> Like all TeX `\special''s, these produce no visible output, and are uninterpreted by TeX itself. They are instructions to DVI processors only. Here, XURL is a standard WWW uniform resource locator (URL), possibly extended with a `#TYPE.STRING' construct, where TYPE is `page', `section', `equation', `reference' (for bibliographic references), `figure', `table', etc. For example, \special{html:<a href="http://www.maths.tcd.ie/~tim/ch1.dvi#equation.1.1">} is a link to equation (1.1) in an example document by Tim Murphy. See `http://www.w3.org/hypertext/WWW/Addressing/Addressing.html' for a precise description of base URL's. (That itself is a URL, in case you were wondering.) Descriptions of the `\special''s: `href' Creates links in your TeX document. For example: \special{html:<a href="http://www.tug.org/">}\TeX\ Users Group\special{html:</a>} The user will be able to click on the text `TeX Users Group' while running Xdvi and get to the TUG home page. (By the way, this is for illustration. In practice, you most likely want to use macros to insert the `\special' commands; reference above.) `name' Defines URL targets in your TeX documents, so links can be resolved. For example: \special{html:<a name="#paradise">}Paradise\special{html:</a>} is exactly where you are right now. This will resolve an `href="paradise"'. `img' Links to an arbitrary external file. Interactively, a viewer is spawned to read the file according to the file extension and your `mailcap' file (see the Xdvi documentation). `base' Defines a base URL that is prepended to all the `name' targets. Typically unnecessary, as the name of the DVI file being read is used by default. The `img' and `base' tags are not yet implemented in Dvips or the NeXTSTEP DVI viewer. File: dvips.info, Node: PostScript fonts, Next: Color, Prev: Interaction with PostScript, Up: Top PostScript fonts **************** Dvips supports the use of PostScript fonts in TeX documents. To use a PostScript font conveniently, you need to prepare a corresponding virtual font; the program Afm2tfm, supplied with Dvips, helps with that. All the necessary support for the standard 35 PostScript fonts (`AvantGarde-Book' through `ZapfDingbats'), plus other freely or commonly available PostScript fonts is available along with Dvips. To use these fonts, you need do nothing beyond what is mentioned in the installation procedure (*note Installation::.). This chapter is therefore relevant only if you are installing new PostScript fonts not supplied with Dvips. (Or if you're curious.) * Menu: * Font concepts:: Metrics, glyphs, virtual fonts, and encodings. * Making a font available:: Installing and using a PostScript font. * Invoking afm2tfm:: Creating TFM and AFM files for a virtual font. * psfonts.map:: Defining available PostScript fonts. File: dvips.info, Node: Font concepts, Next: Making a font available, Up: PostScript fonts Font concepts ============= The information needed to typeset using a particular font is contained in two files: a "metric file" that contains shape-independent information and a "glyph file" that contains the actual shapes of the font's characters. A "virtual font" is an optional additional file that can specify special ways to construct the characters. TeX itself (or LaTeX) look only at the metric file, but DVI drivers such as Dvips look at all three of these files. An "encoding file" defines the correspondence between the code numbers of the characters in a font and their descriptive names. Two encoding files used together can describe a reencoding that rearranges, i.e., renumbers, the characters of a font. * Menu: * Metric files:: Shape-independent font information. * Glyph files:: Character shapes. * Virtual fonts:: Constructing one font from others. * Encodings:: Character codes and character names. * PostScript typesetting:: How PostScript typesets a character.